/**
 * 
 */
package org.xlab.baseframework.dao.api;

import java.io.Serializable;
import java.util.Collection;
import java.util.List;

import org.xlab.baseframework.common.entity.PageinationEntity;
import org.xlab.baseframework.exception.ObjectNotFoundException;
import org.xlab.baseframework.exception.TooManyObjectsFoundException;


/**
 * <p>
 * 所有DAO接口的父类,该接口的实现类为泛型DAO,所有其他DAO接口应当继承自该泛型DAO接口
 * </p>
 * 
 * @author MaKuBEX E-mail:makubexnet@gmail.com
 * @version 1.0.0 at Jul 31, 2009 2:14:08 PM
 * 
 */
public interface IBaseDAO<T, PK extends Serializable> {
	/**
	 * <p>
	 * 获取全部内容(不分页)
	 * </p>
	 * 
	 * @return 全部列表
	 * @throws ObjectNotFoundException
	 *             如果没有找到任何记录时
	 */
	public List<T> findAll() throws ObjectNotFoundException;

	/**
	 * <p>
	 * 获取全部内容(进行分页)
	 * </p>
	 * 
	 * @param page
	 *            分页信息
	 * @return 全部列表
	 * @throws ObjectNotFoundException
	 *             如果没有找到任何记录时
	 */
	public List<T> findAll(PageinationEntity page)
			throws ObjectNotFoundException;

	/**
	 * <p>
	 * 根据实体例子进行精确查询(不分页)
	 * </p>
	 * 
	 * @param exampleInstance
	 *            实体例子
	 * @return 符合例子的列表
	 * @throws ObjectNotFoundException
	 *             如果没有找到任何记录时
	 */
	public List<T> findAllByExample(T exampleInstance)
			throws ObjectNotFoundException;

	/**
	 * <p>
	 * 根据实体例子进行精确查询(进行分页)
	 * </p>
	 * 
	 * @param exampleInstance
	 *            实体例子
	 * @param page
	 *            分页信息
	 * @return 符合例子的列表
	 * @throws ObjectNotFoundException
	 *             如果没有找到任何记录时
	 */
	public List<T> findAllByExample(T exampleInstance, PageinationEntity page)
			throws ObjectNotFoundException;

	/**
	 * <p>
	 * 根据提供的属性名称以及对应的值查找实体集合
	 * </p>
	 * 
	 * @param propertyName
	 *            属性名称
	 * @param value
	 *            属性值
	 * @return 符合条件的实例集合
	 * @throws ObjectNotFoundException
	 *             如果没有找到任何记录时
	 */
	public List<T> findAllByProperty(String propertyName, Object value)
			throws ObjectNotFoundException;

	/**
	 * <p>
	 * 根据主键获取一个已经被序列化的对象
	 * </p>
	 * 
	 * @param id
	 *            对象主键
	 * @return 单个对象
	 * @throws ObjectNotFoundException
	 *             如果没有找到任何记录时
	 */
	public T findById(PK id) throws ObjectNotFoundException;

	/**
	 * <p>
	 * 从一个不可重复属性值中获取对象
	 * </p>
	 * 
	 * @param uniqueProperty
	 *            不可重复的属性名
	 * @param value
	 *            属性值
	 * @return 实体对象
	 * @throws ObjectNotFoundException
	 *             如果没有对应的实体对象
	 * @throws TooManyObjectsFoundException
	 *             如果找到多于一个的记录集
	 */
	public T findByUniqueProperty(String uniqueProperty, Object value)
			throws ObjectNotFoundException, TooManyObjectsFoundException;

	/**
	 * <p>
	 * 合并一个已经被序列化的对象
	 * </p>
	 * 
	 * @param detachedInstance
	 *            已经被序列化的对象
	 * @return 合并后的对象
	 */
	public T merge(T detachedInstance);

	/**
	 * <p>
	 * 删除一个已经被序列化的对象
	 * </p>
	 * 
	 * @param persistentInstance
	 *            需要被删除的对象
	 */
	public void remove(T persistentInstance);

	/**
	 * <p>
	 * 删除一系列已经被序列化的对象
	 * </p>
	 * 
	 * @param persistentInstances
	 *            需要被删除的对象集合
	 */
	public void removeAll(Collection<T> persistentInstances);

	/**
	 * <p>
	 * 保存一个需要被序列化的对象
	 * </p>
	 * 
	 * @param transientInstance
	 *            需要被序列化的对象
	 */
	public void save(T transientInstance);

	/**
	 * <p>
	 * 保存一个需要被序列化的对象，如果该对象已经被序列化过，则更新该对象
	 * </p>
	 * 
	 * @param instance
	 *            需要被保存/更新的对象
	 */
	public void saveOrUpdate(T instance);

	/**
	 * <p>
	 * 保存一系列需要被序列化的对象，如果这些对象已经被序列化过，则更新这些对象
	 * </p>
	 * 
	 * @param instanceList
	 *            需要被保存/更新的对象集合
	 */
	public void saveOrUpdateAll(Collection<T> instanceList);

	/**
	 * <p>
	 * 更新一个已经被序列化的对象
	 * </p>
	 * 
	 * @param persistentInstance
	 *            需要被更新的对象
	 */
	public void update(T persistentInstance);
}